Expand description
Axum Test is a library for writing tests for web servers written using Axum:
- You create a
TestServer
within a test, - use that to build
TestRequest
against your application, - receive back a
TestResponse
, - then assert the response is how you expect.
It includes built in support for serializing and deserializing request and response bodies using Serde, support for cookies and headers, and other common bits you would expect.
TestServer
will pass http requests directly to the handler,
or can be run on a random IP / Port address.
§Getting Started
Create a TestServer
running your Axum Router
:
use ::axum::Router;
use ::axum::extract::Json;
use ::axum::routing::put;
use ::axum_test::TestServer;
use ::serde_json::json;
use ::serde_json::Value;
async fn route_put_user(Json(user): Json<Value>) -> () {
// todo
}
let my_app = Router::new()
.route("/users", put(route_put_user));
let server = TestServer::new(my_app)?;
Then make requests against it:
let response = server.put("/users")
.json(&json!({
"username": "Terrance Pencilworth",
}))
.await;
§Features
§Auto Cookie Saving 🍪
This feature allows the server to save cookies and reuse these on future requests. For example saving session cookies, like a browser would.
This feature is disabled by default, and can be enabled by setting save_cookies
to true on the TestServerConfig
,
and passing this to the TestServer
on construction.
use ::axum::Router;
use ::axum_test::TestServer;
use ::axum_test::TestServerConfig;
let my_app = Router::new();
let config = TestServerConfig::builder()
.save_cookies()
.build();
let server = TestServer::new_with_config(my_app, config)?;
When you make a request, any cookies returned will be reused by the next request, created by that same server.
You can turn this on or off per request, using TestRequest::do_save_cookies
and TestRequest::do_not_save_cookies
.
§Content Type 📇
When performing a request, it will start with no content type at all.
You can set a default type for all TestRequest
objects to use,
by setting the default_content_type
in the TestServerConfig
.
When creating the TestServer
instance, using new_with_config
.
use ::axum::Router;
use ::axum_test::TestServer;
use ::axum_test::TestServerConfig;
let my_app = Router::new();
let config = TestServerConfig::builder()
.default_content_type("application/json")
.build();
let server = TestServer::new_with_config(my_app, config)?;
If there is no default, then a TestRequest
will try to guess the content type.
Such as setting application/json
when calling TestRequest::json
,
and text/plain
when calling TestRequest::text
.
This will never override any default content type provided.
Finally on each TestRequest
, one can set the content type to use.
By calling TestRequest::content_type
on it.
use ::axum::Router;
use ::axum::extract::Json;
use ::axum::routing::put;
use ::axum_test::TestServer;
use ::serde_json::json;
use ::serde_json::Value;
async fn put_user(Json(user): Json<Value>) -> () {
// todo
}
let my_app = Router::new()
.route("/users", put(put_user));
let server = TestServer::new(my_app)?;
let response = server.put("/users")
.content_type(&"application/json")
.json(&json!({
"username": "Terrance Pencilworth",
}))
.await;
§Fail Fast ⚡️
This library includes a mode to have requests panic if they are outside of the 2xx range,
unless marked by calling TestRequest::expect_failure()
.
This is intentional to aid with writing tests, and to help catch errors quickly when making code changes.
This behaviour is off by default, and can be enabled by setting TestServerConfig::expect_success_by_default
to true
when creating a new TestServer
.
Re-exports§
pub use ::http;
Modules§
- This supplies the building blocks for sending multipart forms using
TestRequest::multipart()
.
Structs§
- A
TestRequest
is for building and executing a HTTP request to theTestServer
. - The
TestResponse
is the result of a request created using aTestServer
. TheTestServer
builds aTestRequest
, which when awaited, will produce the response. - The
TestServer
runs your Axum application, allowing you to make HTTP requests against it. - This is for customising the
TestServer
on construction. - This is for easing the building of
TestServerConfig
.
Enums§
- Transport is for setting which transport mode for the
TestServer
to use when making requests.